<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en-US">
<head>
<!-- GenHTML revision 25226-->
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<title>Managing Entities - The Java EE 6 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2011-03-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/javaeetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td width="400px"><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnaph.html">4.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="giepx.html">5.&nbsp;&nbsp;Introduction to Facelets</a></p>
<p class="toc level2"><a href="gjddd.html">6.&nbsp;&nbsp;Expression Language</a></p>
<p class="toc level2"><a href="bnaqz.html">7.&nbsp;&nbsp;Using JavaServer Faces Technology in Web Pages</a></p>
<p class="toc level2"><a href="gjcut.html">8.&nbsp;&nbsp;Using Converters, Listeners, and Validators</a></p>
<p class="toc level2"><a href="bnatx.html">9.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkmaa.html">10.&nbsp;&nbsp;JavaServer Faces Technology Advanced Concepts</a></p>
<p class="toc level2"><a href="bnawo.html">11.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level2"><a href="gkiow.html">12.&nbsp;&nbsp;Using Ajax with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkhxa.html">13.&nbsp;&nbsp;Advanced Composite Components</a></p>
<p class="toc level2"><a href="bnavg.html">14.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnafd.html">15.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnaxu.html">16.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="gijti.html">17.&nbsp;&nbsp;Introduction to Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">18.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="giepu.html">19.&nbsp;&nbsp;Building RESTful Web Services with JAX-RS</a></p>
<p class="toc level2"><a href="gjjxe.html">20.&nbsp;&nbsp;Advanced JAX-RS Features</a></p>
<p class="toc level2"><a href="gkojl.html">21.&nbsp;&nbsp;Running the Advanced JAX-RS Example Application</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijsz.html">22.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijre.html">23.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="gijrb.html">24.&nbsp;&nbsp;Running the Enterprise Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">25.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level2"><a href="gkcqz.html">26.&nbsp;&nbsp;Using the Embedded Enterprise Bean Container</a></p>
<p class="toc level2"><a href="gkidz.html">27.&nbsp;&nbsp;Using Asynchronous Method Invocation in Session Beans</a></p>
<p class="toc level1 tocsp"><a href="gjbnr.html">Part&nbsp;V&nbsp;Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="giwhb.html">28.&nbsp;&nbsp;Introduction to Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="gjbls.html">29.&nbsp;&nbsp;Running the Basic Contexts and Dependency Injection Examples</a></p>
<p class="toc level2"><a href="gjehi.html">30.&nbsp;&nbsp;Contexts and Dependency Injection for the Java EE Platform: Advanced Topics</a></p>
<p class="toc level2"><a href="gkhre.html">31.&nbsp;&nbsp;Running the Advanced Contexts and Dependency Injection Examples</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;VI&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">32.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level3"><a href="bnbqa.html">Entities</a></p>
<p class="toc level4"><a href="bnbqa.html#bnbqb">Requirements for Entity Classes</a></p>
<p class="toc level4"><a href="bnbqa.html#bnbqc">Persistent Fields and Properties in Entity Classes</a></p>
<p class="toc level5"><a href="bnbqa.html#bnbqd">Persistent Fields</a></p>
<p class="toc level5"><a href="bnbqa.html#bnbqe">Persistent Properties</a></p>
<p class="toc level5"><a href="bnbqa.html#giqvn">Using Collections in Entity Fields and Properties</a></p>
<p class="toc level5"><a href="bnbqa.html#gkahq">Validating Persistent Fields and Properties</a></p>
<p class="toc level4 tocsp"><a href="bnbqa.html#bnbqf">Primary Keys in Entities</a></p>
<p class="toc level4"><a href="bnbqa.html#bnbqh">Multiplicity in Entity Relationships</a></p>
<p class="toc level4"><a href="bnbqa.html#bnbqi">Direction in Entity Relationships</a></p>
<p class="toc level5"><a href="bnbqa.html#bnbqj">Bidirectional Relationships</a></p>
<p class="toc level5"><a href="bnbqa.html#bnbqk">Unidirectional Relationships</a></p>
<p class="toc level5"><a href="bnbqa.html#bnbql">Queries and Relationship Direction</a></p>
<p class="toc level5"><a href="bnbqa.html#bnbqm">Cascade Operations and Relationships</a></p>
<p class="toc level5"><a href="bnbqa.html#giqxy">Orphan Removal in Relationships</a></p>
<p class="toc level4 tocsp"><a href="bnbqa.html#gjiwz">Embeddable Classes in Entities</a></p>
<p class="toc level3 tocsp"><a href="bnbqn.html">Entity Inheritance</a></p>
<p class="toc level4"><a href="bnbqn.html#bnbqo">Abstract Entities</a></p>
<p class="toc level4"><a href="bnbqn.html#bnbqp">Mapped Superclasses</a></p>
<p class="toc level4"><a href="bnbqn.html#bnbqq">Non-Entity Superclasses</a></p>
<p class="toc level4"><a href="bnbqn.html#bnbqr">Entity Inheritance Mapping Strategies</a></p>
<p class="toc level5"><a href="bnbqn.html#bnbqs">The Single Table per Class Hierarchy Strategy</a></p>
<p class="toc level5"><a href="bnbqn.html#bnbqu">The Table per Concrete Class Strategy</a></p>
<p class="toc level5"><a href="bnbqn.html#bnbqv">The Joined Subclass Strategy</a></p>
<div id="scrolltoc" class="onpage">
<p class="toc level3 tocsp"><a href="">Managing Entities</a></p>
<p class="toc level4"><a href="#bnbqy">The <tt>EntityManager</tt> Interface</a></p>
<p class="toc level5"><a href="#bnbqz">Container-Managed Entity Managers</a></p>
<p class="toc level5"><a href="#bnbra">Application-Managed Entity Managers</a></p>
<p class="toc level5"><a href="#bnbrb">Finding Entities Using the <tt>EntityManager</tt></a></p>
<p class="toc level5"><a href="#bnbrc">Managing an Entity Instance's Lifecycle</a></p>
<p class="toc level5"><a href="#bnbrd">Persisting Entity Instances</a></p>
<p class="toc level5"><a href="#bnbre">Removing Entity Instances</a></p>
<p class="toc level5"><a href="#bnbrf">Synchronizing Entity Data to the Database</a></p>
<p class="toc level4 tocsp"><a href="#bnbrj">Persistence Units</a></p>
</div>
<p class="toc level3 tocsp"><a href="gjise.html">Querying Entities</a></p>
<p class="toc level3"><a href="gkclc.html">Further Information about Persistence</a></p>
<p class="toc level2 tocsp"><a href="gijst.html">33.&nbsp;&nbsp;Running the Persistence Examples</a></p>
<p class="toc level2"><a href="bnbtg.html">34.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level2"><a href="gjitv.html">35.&nbsp;&nbsp;Using the Criteria API to Create Queries</a></p>
<p class="toc level2"><a href="gkjiq.html">36.&nbsp;&nbsp;Creating and Using String-Based Criteria Queries</a></p>
<p class="toc level2"><a href="gkjjf.html">37.&nbsp;&nbsp;Controlling Concurrent Access to Entity Data with Locking</a></p>
<p class="toc level2"><a href="gkjia.html">38.&nbsp;&nbsp;Improving the Performance of Java Persistence API Applications By Setting a Second-Level Cache</a></p>
<p class="toc level1 tocsp"><a href="gijrp.html">Part&nbsp;VII&nbsp;Security</a></p>
<p class="toc level2"><a href="bnbwj.html">39.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bncas.html">40.&nbsp;&nbsp;Getting Started Securing Web Applications</a></p>
<p class="toc level2"><a href="bnbyk.html">41.&nbsp;&nbsp;Getting Started Securing Enterprise Applications</a></p>
<p class="toc level1 tocsp"><a href="gijue.html">Part&nbsp;VIII&nbsp;Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="gijto.html">42.&nbsp;&nbsp;Introduction to Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="bncih.html">43.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">44.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncdq.html">45.&nbsp;&nbsp;Java Message Service Concepts</a></p>
<p class="toc level2"><a href="bncgv.html">46.&nbsp;&nbsp;Java Message Service Examples</a></p>
<p class="toc level2"><a href="gkahp.html">47.&nbsp;&nbsp;Advanced Bean Validation Concepts and Examples</a></p>
<p class="toc level2"><a href="gkeed.html">48.&nbsp;&nbsp;Using Java EE Interceptors</a></p>
<p class="toc level1 tocsp"><a href="gkgjw.html">Part&nbsp;IX&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="gkaee.html">49.&nbsp;&nbsp;Duke's Tutoring Case Study Example</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td>
         <div class="header">
             <div class="banner">
                <table width="100%" border="0" cellpadding="5" cellspacing="0">
                   <tbody>
                      <tr>
                         <td valign="bottom"><p class="Banner">The Java EE 6 Tutorial
</p></td>
                         <td align="right"  valign="bottom"><img src="graphics/javalogo.png" alt="Java Coffee Cup logo"></td>
                      </tr>
                   </tbody>
                </table>
             </div>

             <div class="header-links">
	         <a href="./index.html">Home</a> | 
<a href="../information/download.html">Download</a> | 
<a href="./javaeetutorial6.pdf">PDF</a> | 
<a href="../information/faq.html">FAQ</a> | 
<a href="http://download.oracle.com/javaee/feedback.htm">Feedback</a>

             </div>
             <div class="navigation">
                 <a href="bnbqn.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
                 <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
                 <a href="gjise.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="bnbqw"></a><h2>Managing Entities</h2>
<a name="indexterm-1651"></a><a name="indexterm-1652"></a><p>Entities are managed by the entity manager, which is represented by <tt>javax.persistence.EntityManager</tt>
instances. Each <tt>EntityManager</tt> instance is associated with a persistence context: a set of
managed entity instances that exist in a particular data store. A persistence context
defines the scope under which particular entity instances are created, persisted, and removed.
The <tt>EntityManager</tt> interface defines the methods that are used to interact with the
persistence context.</p>



<a name="bnbqy"></a><h3>The <tt>EntityManager</tt> Interface</h3>
<a name="indexterm-1653"></a><p>The <tt>EntityManager</tt> API creates and removes persistent entity instances, finds entities by the
entity&rsquo;s primary key, and allows queries to be run on entities.</p>



<a name="bnbqz"></a><h4>Container-Managed Entity Managers</h4>
<a name="indexterm-1654"></a><p>With a <b>container-managed entity manager</b>, an <tt>EntityManager</tt> instance&rsquo;s persistence context is automatically propagated by the
container to all application components that use the <tt>EntityManager</tt> instance within a
single Java Transaction API (JTA) transaction.</p>

<p><a name="indexterm-1655"></a>JTA transactions usually involve calls across application components. To complete a JTA transaction,
these components usually need access to a single persistence context. This occurs when
an <tt>EntityManager</tt> is injected into the application components by means of the <tt>javax.persistence.PersistenceContext</tt>
annotation. The persistence context is automatically propagated with the current JTA transaction, and
<tt>EntityManager</tt> references that are mapped to the same persistence unit provide access to
the persistence context within that transaction. By automatically propagating the persistence context, application components
don&rsquo;t need to pass references to <tt>EntityManager</tt> instances to each other in
order to make changes within a single transaction. The Java EE container manages
the lifecycle of container-managed entity managers.</p>

<p>To obtain an <tt>EntityManager</tt> instance, inject the entity manager into the application component:</p>

<pre>@PersistenceContext
EntityManager em;</pre>

<a name="bnbra"></a><h4>Application-Managed Entity Managers</h4>
<a name="indexterm-1656"></a><a name="indexterm-1657"></a><p>With an <b>application-managed entity manager</b>, on the other hand, the persistence context is not propagated
to application components, and the lifecycle of <tt>EntityManager</tt> instances is managed by the application.</p>

<p>Application-managed entity managers are used when applications need to access a persistence context
that is not propagated with the JTA transaction across <tt>EntityManager</tt> instances in a
particular persistence unit. In this case, each <tt>EntityManager</tt> creates a new, isolated persistence context.
The <tt>EntityManager</tt> and its associated persistence context are created and destroyed explicitly by the
application. They are also used when directly injecting <tt>EntityManager</tt> instances can&rsquo;t be
done because <tt>EntityManager</tt> instances are not thread-safe. <tt>EntityManagerFactory</tt> instances are thread-safe.</p>

<p>Applications create <tt>EntityManager</tt> instances in this case by using the <tt>createEntityManager</tt> method of <tt>javax.persistence.EntityManagerFactory</tt>.</p>

<p><a name="indexterm-1658"></a>To obtain an <tt>EntityManager</tt> instance, you first must obtain an <tt>EntityManagerFactory</tt> instance by injecting
it into the application component by means of the <tt>javax.persistence.PersistenceUnit</tt> annotation:</p>

<pre>@PersistenceUnit
EntityManagerFactory emf;</pre><p>Then obtain an <tt>EntityManager</tt> from the <tt>EntityManagerFactory</tt> instance:</p>

<pre>EntityManager em = emf.createEntityManager();</pre><p>Application-managed entity managers don&rsquo;t automatically propagate the JTA transaction context. Such applications need
to manually gain access to the JTA transaction manager and add transaction demarcation
information when performing entity operations. The <tt>javax.transaction.UserTransaction</tt> interface defines methods to begin, commit,
and roll back transactions. Inject an instance of <tt>UserTransaction</tt> by creating an instance variable
annotated with <tt>@Resource</tt>:</p>

<pre>@Resource
UserTransaction utx;</pre><p>To begin a transaction, call the <tt>UserTransaction.begin</tt> method. When all the entity operations
are complete, call the <tt>UserTransaction.commit</tt> method to commit the transaction. The <tt>UserTransaction.rollback</tt>
method is used to roll back the current transaction.</p>

<p>The following example shows how to manage transactions in an application that uses
an application-managed entity manager:</p>

<pre>@PersistenceContext
EntityManagerFactory emf;
EntityManager em;
@Resource
UserTransaction utx;
...
em = emf.createEntityManager();
try {
  utx.begin();
  em.persist(SomeEntity);
  em.merge(AnotherEntity);
  em.remove(ThirdEntity);
  utx.commit();
} catch (Exception e) {
  utx.rollback();
}</pre>

<a name="bnbrb"></a><h4>Finding Entities Using the <tt>EntityManager</tt></h4>
<a name="indexterm-1659"></a><p>The <tt>EntityManager.find</tt> method is used to look up entities in the data store
by the entity&rsquo;s primary key:</p>

<pre>@PersistenceContext
EntityManager em;
public void enterOrder(int custID, Order newOrder) {
    Customer cust = em.find(Customer.class, custID);
    cust.getOrders().add(newOrder);
    newOrder.setCustomer(cust);
}</pre>

<a name="bnbrc"></a><h4>Managing an Entity Instance&rsquo;s Lifecycle</h4>
<a name="indexterm-1660"></a><p>You manage entity instances by invoking operations on the entity by means of
an <tt>EntityManager</tt> instance. Entity instances are in one of four states: new, managed,
detached, or removed.</p>


<ul><li><p>New entity instances have no persistent identity and are not yet associated with a persistence context.</p>

</li>
<li><p>Managed entity instances have a persistent identity and are associated with a persistence context.</p>

</li>
<li><p>Detached entity instances have a persistent identity and are not currently associated with a persistence context.</p>

</li>
<li><p>Removed entity instances have a persistent identity, are associated with a persistent context, and are scheduled for removal from the data store.</p>

</li></ul>


<a name="bnbrd"></a><h4>Persisting Entity Instances</h4>
<a name="indexterm-1661"></a><p>New entity instances become managed and persistent either by invoking the <tt>persist</tt> method
or by a cascading <tt>persist</tt> operation invoked from related entities that have the
<tt>cascade=PERSIST</tt> or <tt>cascade=ALL</tt> elements set in the relationship annotation. This means that the
entity&rsquo;s data is stored to the database when the transaction associated with the
<tt>persist</tt> operation is completed. If the entity is already managed, the <tt>persist</tt> operation
is ignored, although the <tt>persist</tt> operation will cascade to related entities that have the
<tt>cascade</tt> element set to <tt>PERSIST</tt> or <tt>ALL</tt> in the relationship annotation. If <tt>persist</tt>
is called on a removed entity instance, the entity becomes managed. If the
entity is detached, either <tt>persist</tt> will throw an <tt>IllegalArgumentException</tt>, or the transaction commit will
fail.</p>

<pre>@PersistenceContext
EntityManager em;
...
public LineItem createLineItem(Order order, Product product,
        int quantity) {
    LineItem li = new LineItem(order, product, quantity);
    order.getLineItems().add(li);
    em.persist(li);
    return li;
}</pre><p>The <tt>persist</tt> operation is propagated to all entities related to the calling entity
that have the <tt>cascade</tt> element set to <tt>ALL</tt> or <tt>PERSIST</tt> in the relationship annotation:</p>

<pre>@OneToMany(cascade=ALL, mappedBy="order")
public Collection&lt;LineItem> getLineItems() {
    return lineItems;
}</pre>

<a name="bnbre"></a><h4>Removing Entity Instances</h4>
<a name="indexterm-1662"></a><p>Managed entity instances are removed by invoking the <tt>remove</tt> method or by a
cascading <tt>remove</tt> operation invoked from related entities that have the <tt>cascade=REMOVE</tt> or <tt>cascade=ALL</tt>
elements set in the relationship annotation. If the <tt>remove</tt> method is invoked on a
new entity, the <tt>remove</tt> operation is ignored, although <tt>remove</tt> will cascade to related
entities that have the <tt>cascade</tt> element set to <tt>REMOVE</tt> or <tt>ALL</tt> in the
relationship annotation. If <tt>remove</tt> is invoked on a detached entity, either <tt>remove</tt> will
throw an <tt>IllegalArgumentException</tt>, or the transaction commit will fail. If invoked on an already
removed entity, <tt>remove</tt> will be ignored. The entity&rsquo;s data will be removed from
the data store when the transaction is completed or as a result of
the <tt>flush</tt> operation.</p>

<pre>public void removeOrder(Integer orderId) {
    try {
        Order order = em.find(Order.class, orderId);
        em.remove(order);
    }...</pre><p>In this example, all <tt>LineItem</tt> entities associated with the order are also removed,
as <tt>Order.getLineItems</tt> has <tt>cascade=ALL</tt> set in the relationship annotation.</p>



<a name="bnbrf"></a><h4>Synchronizing Entity Data to the Database</h4>
<a name="indexterm-1663"></a><p>The state of persistent entities is synchronized to the database when the transaction
with which the entity is associated commits. If a managed entity is in
a bidirectional relationship with another managed entity, the data will be persisted, based
on the owning side of the relationship.</p>

<p>To force synchronization of the managed entity to the data store, invoke the
<tt>flush</tt> method of the <tt>EntityManager</tt> instance. If the entity is related to another
entity and the relationship annotation has the <tt>cascade</tt> element set to <tt>PERSIST</tt> or
<tt>ALL</tt>, the related entity&rsquo;s data will be synchronized with the data store when
<tt>flush</tt> is called.</p>

<p>If the entity is removed, calling <tt>flush</tt> will remove the entity data from
the data store.</p>



<a name="bnbrj"></a><h3>Persistence Units</h3>
<a name="indexterm-1664"></a><a name="indexterm-1665"></a><p>A persistence unit defines a set of all entity classes that are
managed by <tt>EntityManager</tt> instances in an application. This set of entity classes represents the
data contained within a single data store.</p>

<p><a name="indexterm-1666"></a>Persistence units are defined by the <tt>persistence.xml</tt> configuration file. The following is an
example <tt>persistence.xml</tt> file:</p>

<pre>&lt;persistence>
    &lt;persistence-unit name="OrderManagement">
        &lt;description>This unit manages orders and customers.
            It does not rely on any vendor-specific features and can
            therefore be deployed to any persistence provider.
        &lt;/description>
        &lt;jta-data-source>jdbc/MyOrderDB&lt;/jta-data-source>
        &lt;jar-file>MyOrderApp.jar&lt;/jar-file>
        &lt;class>com.widgets.Order&lt;/class>
        &lt;class>com.widgets.Customer&lt;/class>
    &lt;/persistence-unit>
&lt;/persistence></pre><p>This file defines a persistence unit named <tt>OrderManagement</tt>, which uses a JTA-aware data
source: <tt>jdbc/MyOrderDB</tt>. The <tt>jar-file</tt> and <tt>class</tt> elements specify managed persistence classes: entity classes,
embeddable classes, and mapped superclasses. The <tt>jar-file</tt> element specifies JAR files that
are visible to the packaged persistence unit that contain managed persistence classes, whereas
the <tt>class</tt> element explicitly names managed persistence classes.</p>

<p>The <tt>jta-data-source</tt> (for JTA-aware data sources) and <tt>non-jta-data-source</tt> (for non-JTA-aware data sources) elements specify
the global JNDI name of the data source to be used by
the container.</p>

<p>The JAR file or directory whose <tt>META-INF</tt> directory contains <tt>persistence.xml</tt> is called the
root of the persistence unit. The scope of the persistence unit is determined
by the persistence unit&rsquo;s root. Each persistence unit must be identified with a
name that is unique to the persistence unit&rsquo;s scope.</p>

<p>Persistent units can be packaged as part of a WAR or EJB
JAR file or can be packaged as a JAR file that can then
be included in an WAR or EAR file.</p>


<ul><li><p>If you package the persistent unit as a set of classes in an EJB JAR file, <tt>persistence.xml</tt> should be put in the EJB JAR&rsquo;s <tt>META-INF</tt> directory.</p>

</li>
<li><p>If you package the persistence unit as a set of classes in a WAR file, <tt>persistence.xml</tt> should be located in the WAR file&rsquo;s <tt>WEB-INF/classes/META-INF</tt> directory.</p>

</li>
<li><p>If you package the persistence unit in a JAR file that will be included in a WAR or EAR file, the JAR file should be located in either</p>


<ul><li><p>The <tt>WEB-INF/lib</tt> directory of a WAR</p>

</li>
<li><p>The EAR file&rsquo;s library directory</p>


<hr><p><b>Note - </b>In the Java Persistence API 1.0, JAR files could be located at the root of an EAR file as the root of the persistence unit. This is no longer supported. Portable applications should use the EAR file&rsquo;s library directory as the root of the persistence unit.</p>


<hr>
</li></ul>
</li></ul>

         </div>
         <div class="navigation">
             <a href="bnbqn.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
             <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
             <a href="gjise.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
         </div>

         <div class="copyright">
      	    <p>Copyright &copy; 2011, Oracle and/or its affiliates. All rights reserved. <a href="docinfo.html">Legal Notices</a></p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

